docs: expand contributor docs and restructure issue templates - #114
Merged
Conversation
- Add AGENTS.md following the agents.md spec for coding-agent guidance - Expand CONTRIBUTING.md from a brief overview into a detailed reference: full field tables (required/recommended/optional), transport + input + auth guidance, review criteria, trademark policy, security expectations, and troubleshooting for common validation errors - Rewrite PULL_REQUEST_TEMPLATE.md as a structured Add-Server template covering CI-enforced checks, reviewer quality bar, platform-managed fields, and trademark acknowledgements - Add request-server.yml so the community can ask for servers they don't have a definition for (label: server-request, title: "[Request] ") - Add bug-report.yml for flagging broken or incorrect existing definitions (label: bug, title: "[Bug] ") - Add config.yml to disable blank issues and lead the "New issue" chooser with the CONTRIBUTING (PR) path - Remove submit-server.yml; issue forms cannot open PRs, which made the template a slower and confusing path. Adding a server is now PR-only via the CONTRIBUTING quickstart. request-server.yml and bug-report.yml are deep-linked from the McpMux desktop app, so their filenames must stay stable. Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>
3 tasks
its-mash
added a commit
that referenced
this pull request
Apr 23, 2026
Two follow-ups that were part of PR #114's branch but did not make it into the squash merge: - `.github/ISSUE_TEMPLATE/config.yml` — flip `blank_issues_enabled` from `false` to `true` so anyone (not just maintainers) can open a blank issue from the "New issue" chooser. Without the flag, non- maintainers only see the structured templates. - `.github/ISSUE_TEMPLATE/request-server.yml` — replace the outdated "use the Submit a Server template (or open a PR)" hint. The Submit-a-Server template was removed in the prior PR because issue forms can't create PRs; repoint readers straight at CONTRIBUTING.md's quickstart instead. Signed-off-by: Mohammod Al Amin Ashik <maa.ashik00@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Upgrades the contributor experience for the registry:
AGENTS.md— new, following the agents.md spec. Gives coding agents a concise map of the repo: layout, commands, server-definition rules, platform-managed fields, trademark policy, and "things not to do".CONTRIBUTING.md— expanded from a ~125-line overview into a ~670-line reference. Full field tables (required / recommended / optional), transport anatomy (stdio + http), input placeholders with every schema type,obtainblock guidance, auth types, category list, capability semantics, platform-managed fields, validation command outputs, PR workflow, review criteria, trademark policy, security expectations, and a troubleshooting section covering the seven most common validation errors.PULL_REQUEST_TEMPLATE.md— rewritten as a structured Add-Server template. Splits the checklist into CI-enforced (maps 1:1 tovalidate-pr.yml), reviewer quality bar, platform-managed fields you must not set, and trademark acknowledgements.request-server.yml(new) — community asks for servers they don't have a definition for. Labelserver-request, title[Request].bug-report.yml(new) — flags broken or incorrect existing definitions. Labelbug, title[Bug].config.yml(new) — disables blank issues; leads the "New issue" chooser with the CONTRIBUTING (PR) path, then Discussions, then the live registry.submit-server.yml(removed) — issue forms can't open PRs, which made the template a slower, confusing path. Adding a server is now PR-only via the CONTRIBUTING quickstart.Why
submit-server.ymlrequired a maintainer to manually turn each form into a JSON file + PR — slow and unnecessary when contributors can just fork and PR directly.CONTRIBUTING.mdomitted most of the schema surface contributors actually need (input types, auth wiring,obtainblocks, platform-managed fields). Those gaps showed up repeatedly in PR review.AGENTS.mdsurfaces the same guidance for coding agents working on this repo, consistent with the pattern inmcp-mux.Coordination notes
request-server.ymlandbug-report.ymlare deep-linked from the McpMux desktop app's Request / Report buttons and frommcp-mux/.github/ISSUE_TEMPLATE/config.yml. Their filenames must stay stable — renaming breaks links in every installed build of McpMux.CONTRIBUTING.mdin this repo, so the quickstart there is the landing page for new contributors.Test plan
Validate PR) is green — this PR doesn't touchservers/, so the workflow should skip or no-op.?template=request-server.ymland?template=bug-report.ymlURLs resolve to the new templates (this is what the desktop app links to).CONTRIBUTING.mdrenders cleanly on github.com (headings, tables, code fences, anchor links in the TOC).AGENTS.mdrenders cleanly on github.com.